Managing Python Virtual Environments with UV

PyData Northern Utah | ASC Innovation Lab

Marc Dotson and Kaden Buffaloe

Background

What is a Python environment?

A Python environment is composed of the Python version and library versions (including dependencies)

Why manage your Python environments?

It is not uncommon for different projects to require different Python versions and different library versions

Why manage your Python environments?

It is not uncommon for different projects to require different Python versions and different library versions

Welcome to “dependency hell”

What makes a Python environment virtual?

A Python virtual environment (a.k.a., a project environment) is a self-contained, project-specific environment

My code works on my machine, so what?

Project environments can be reproduced on another machine by you (including future you) or someone else

  1. Code
  2. Code, Python version, and library versions
  3. Code, Python version, library versions, and OS

My code works on my machine, so what?

Project environments can be reproduced on another machine by you (including future you) or someone else

  1. Code
  2. Code, Python version, and library versions
  3. Code, Python version, library versions, and OS

If you need to reproduce something about your machine beyond your code, Python version, and library versions, you’ll want to use a container

Why uv?

uv is an extremely fast Python package and project manager, written in Rust

  • A single tool to replace conda, pip, poetry, pyenv, virtualenv, etc.
  • Installable via the command line without Rust or Python
  • Supports macOS, Linux, and Windows
  • Easy to integrate with or transfer from existing tools

Walkthrough

Install uv

Get started by installing uv via the command line (i.e., the programming interface into your OS itself)

macOS and Linux via Terminal

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows via PowerShell

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Run uv in the command line to verify it has been installed

Install and manage Python versions

Once you have uv installed, it’s easy to install and manage Python different versions from the command line:

  • Install the latest stable Python release with uv python install
  • Install a specific Python version, like uv python install 3.13.4
  • View Python versions you can install with uv python list
  • Find which Python versions you have installed with uv python find
  • Uninstall a specific Python version, like uv python uninstall 3.13.4

There’s lots more uv can do to manage Python versions

Create a project directory

Using the command line or a code editor (i.e., VS Code, Cursor, Positron, etc.), locate or create a project directory to use, preferable one that is not being synced to the cloud via OneDrive, iCloud, etc.

macOS and Linux via Terminal

cd ~/Desktop
mkdir uv-practice
cd uv-practice

Windows via PowerShell

cd Desktop
mkdir uv-practice
cd uv-practice

Dragging a folder from your finder/file explorer and dropping it into the terminal/shell will paste its file path

Initialize a project environment

Run uv init to initialize a project environment

uv-practice
├── .python-version
├── main.py
├── pyproject.toml
└── README.md
  • This creates a pyproject.toml file with metadata about the project and a hidden .python-version file that specifies the default version of Python for the project.
  • It also creates main.py and README.md files that you can use or delete.

Install libraries

With the project environment initialized, you can now install libraries. For example, to install the Pandas library, run:

uv add pandas
  • This installs Pandas, and any dependencies, and creates both a uv.lock file that keeps track of the versions of the libraries you’ve installed and a hidden .venv reproducible environment folder that serves as the project library.
  • Whenever you install new libraries, the uv.lock file is automatically updated.

Before Running uv add <package>

my-python-project
├── data
├── figures
├── presentations
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
└── README.md

After Running uv add <package>

my-python-project
├── .venv
├── data
├── figures
├── presentations
├── .gitignore
├── .python-version
├── main.py
├── pyproject.toml
├── README.md
└── uv.lock

Run Code In Your Environment

With packages now installed uv can be used to run code in your environment. No need to activate/deactivate your venv — uv run does it. If the .venv somehow gets deleted uv will check prior to running and re-initailize it.

uv run main.py
import pandas as pd
import matplotlib.pyplot as plt

# --- USU Color Scheme ---
usu_colors = ['#003366','#9D9D9D','#6699CC', '#0055A4' ]

# Load customer data and establish region counts
customer_data = pd.read_csv('../data/customer_data.csv')
region_counts = customer_data['region'].value_counts()

#Plot regional customer distributions
fig, ax = plt.subplots(figsize=(8, 8)) 
region_counts.plot.pie(
    ax=ax,
    autopct='%1.1f%%',
    startangle=90,
    colors=usu_colors[:len(region_counts)])

ax.set_title('Customer Region Distribution', fontsize=16, color='#003366', fontweight='bold')

ax.set_ylabel('')
plt.show()

Run Code In Your Environment

Other Useful Features

uv offers several powerful commands to streamline project management and collaboration.

  • Auto-Install on Run If you’re starting with an existing project, uv run automatically installs any missing libraries from the uv.lock file before executing your code.
# No need to run 'uv sync' first!
uv run python your_script.py
  • Export for Compatibility To share your project with someone using a different tool (like pip), you can export your environment’s dependencies into standard formats.
  • For a requirements.txt file:
uv export --format requirements.txt
  • For a pylock.toml file:
uv export -o pylock.toml

See more in depth use set up at the data stack training

Thank You!